咸鱼开发修炼之路

JPA原生查询(Native Query)

发表于 | 分类于

JPA支持本地查询，所谓本地查询，就是使用原生的sql语句（根据数据库的不同，在sql的语法或结构方面可能有所区别）进行查询数据库的操作。

本地查询主要使用EntityManager接口里的方法：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
public interface EntityManager {
public void persist(Object entity);
public <T> T find(Class <T> entityClass, Object primaryKey);
public <T> T getReference(Class <T> entityClass, Object primaryKey);
public <T> T merge(T entity);
public void remove(Object entity);
public void lock(Object entity, LockModeType lockMode);
public void refresh(Object entity);
public boolean contains(Object entity);
public void clear( );
public void joinTransaction( );
public void flush( );
public FlushModeType getFlushMode( );
public void setFlushMode(FlushModeType type);
public Query createQuery(String queryString);
public Query createNamedQuery(String name);
public Query createNativeQuery(String sqlString);
public Query createNativeQuery(String sqlString, String resultSetMapping);
public Query createNativeQuery(String sqlString, Class resultClass);
public Object getDelegate( );
public void close( );
public boolean isOpen( );
}

即 createNativeQuery方法的三种形式，但用这个方法的缺点是，要将查询的sql语句及返回结果集类型传递进去。还有一种方法是使用createNamedQuery，这样就可以避免在这里直接写入sql语句以及返回的结果集类型等参数，而可以在相关的Entity类里对这些信息进行配置。

1
2
3
4
5
6
//这里只是传递进去一个string值
Query q = em.createNamedQuery("ReturnOrderListWithFullScalarType");
//这里是设定在sql中所需的参数
q.setParameter(1, customer.getId());
//得到结果集
List orderList = q.getResultList();

这个查询主要是根据用户的id 来获取他名下的所有订单。所以，在实体类 Order中，加入相关的native query annotation.
1
2
3
4
5
6
7
8
9
10
11
@NamedNativeQueries
(
    {
       @NamedNativeQuery(
           name="ReturnOrderListWithFullScalarType",
              query="select o.id as order_id,o.create_date as order_creation_date,o.description as order_description,o.sum_price as order_sum_total,
		c.name as customer_name,c.ctype as customer_type,c.id as customer_id from orders o join customer c on o.cust_id=c.id where o.cust_id=?1",
           resultSetMapping="ReturnOrderListWithFullScalarType"),
        。。。。。。。。。。。。。可能还有更多的本地查询设置
	}
)

@NamedNativeQueries 如果在一个实体类中有多个NamedNativeQuery的话，必须使用该批注，并且将单个的NamedNativeQuery都作为NamedNativeQueries数组中的一个元素。
@NamedNativeQuery，在这里设置关于该本地查询的信息。name表示传递进EntityManager.createNamedQuery(“name”)的参数，query表示实施本地查询的sql语句，resultSetMapping表示返回结果集的映射方式。它的意思就是结果集将以哪种形式来保存。

接着，就要设置这个结果集的映射方式了。

一、简单映射

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
@SqlResultSetMappings(
{
    @SqlResultSetMapping
    (
       name="ReturnOrderListWithFullScalarType",
       entities={},
       columns=
       {
           @ColumnResult(name="order_id"),
           @ColumnResult(name="order_creation_date"),
           @ColumnResult(name="order_description"),
           @ColumnResult(name="order_sum_total"),
           @ColumnResult(name="customer_id"),
           @ColumnResult(name="customer_name")
       }
    ),
       。。。。。。。。。。。。。可能还有更多的结果集映射设置
})

针对每一个本地查询的返回值，都有一个结果集和它映射。它可以返回

  1. 实体（包括不同类型的实体，即多个实体） Entity
  2. 标量值 Scalar
  3. 实体与标量值的组合 Entity+Scalar

默认情况下，JPA假设原生sql查询中select语句将会：

  1. 返回一个实体类型
  2. 包含与返回的实体的所有字段或属性相对应的所有列，即列名和实体属性/字段名一样
  3. 查询中没有用列名别名，column alias，即没有用 AS 指定别名

@SqlResultSetMappings，如果在一个实体类中有多个@NamedNativeQuery的话，必然就有多个结果集映射@SqlResultSetMapping。在这种情况下，必须使用该批注，并且将单个的SqlResultSetMapping都作为SqlResultSetMappings数组中的一个元素。
@SqlResultSetMapping，关于结果集映射的详细信息。
name 表示该结果集映射的名字，与@NamedNativeQuery中的resultSetMapping=”ReturnOrderListWithFullScalarType”的值相对应。
entities表示查询结果集会被映射进实体，如果有就要将所有返回的实体一一列出（这里我们将结果集全部映射进标量，所以entities属性是个空数组）。
columns表示将被映射进标量的结果集中的各个列。

这里要说一下标量（Scalar）这个概念。在物理学上，标量与矢量（Vector）是相互对应的，矢量是既有方向又有大小的量，而标量是只有大小的量。在此处，Scalar的含义与物理学上的定义差不多，Scalar可以认为是一个没有属性/方法的单纯的常量(可以想象为java数据类型的primitive type)，而与它相对的则是有方法/属性的对象(object type)。那么采用这种映射机制，我们从数据库取来的每一条记录的每一个字段，仅仅是被单纯的作为一个常量，保存在每一个columnResult中。

@ ColumnResult，就是指在sql语句中，将哪些查询的列保存进来。每一个@ColumnResult对应一个列，name=”order_id” ，注意，如果在select的时候，用AS 制定了列的别名，“order_id” 则表示的是别名。

这种映射方式比较简单，我们可以推测，得到的结果集List中，数据会是这样：
[ {“列1”, “列2”, “列3”, …}, {“列1”, “列2”, “列3”, …}, …… ]

经过运行测试程序，得到了我们的推论
`


*ReturnOrderListWithFullScalarType*
52 2009-05-27 00:00:00.0 This is an order creation example. 36817.0 39 John Smith
55 2009-05-27 00:00:00.0 This is an order creation example. 3347.0 39 John Smith
……

`

二、映射到实体

1
2
3
4
5
6
7
8
9
10
11
@NamedNativeQueries
(
    {
       @NamedNativeQuery(
           name="ReturnOrderListWithFullEntityType",
              query="select o.id as order_id,o.create_date as order_creation_date,o.description as order_description,o.sum_price as order_sum_total,
		c.name as customer_name,c.ctype as customer_type,c.id as customer_id from orders o join customer c on o.cust_id=c.id where o.cust_id=?1",
           resultSetMapping="ReturnOrderListWithFullEntityType"),
        。。。。。。。。。。。。。可能还有更多的本地查询设置
	}
)

改变本地查询的resultSetMapping

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
@SqlResultSetMapping
    (
       name="ReturnOrderListWithFullEntityType",
       entities=
       {
           @EntityResult
           (
              entityClass=entity.Order.class,
              fields=
              {
    @FieldResult(name="id",column="order_id"),
                         @FieldResult(name="date",column="order_creation_date"),
                  @FieldResult(name="desc",column="order_description"),
    @FieldResult(name="sum",column="order_sum_total")
              }
           ),
 
           @EntityResult
           (
              entityClass=entity.Customer.class,
              discriminatorColumn="customer_type",
              fields=
              {
                  @FieldResult(name="id",column="customer_id"),
                  @FieldResult(name="name",column="customer_name")
              }
           )
       },
       columns={}
    )

entities属性是一个包含与返回结果集相映射的所有实体的一个数组。这条查询得到了订单和用户的信息，所以，与结果集映射的实体，就应该是Order和Customer。
每一个映射实体用@EntityResult表示，entityClass表示实体类，fields表示该实体类中的属性，与查询结果中的哪些个列相映射。而每一个“属性<->列”的映射关系，又保存在@FieldResult里面。name是实体属性，column是查询列（或列别名）

要注意的是，如果要将结果集映射到实体对象，则

  1. Select 语句中必须包含实体所映射的表中的PK，也就是 select o.id as order_id

  2. 反过来，“属性<->列”的映射，也必须将表的PK映射到实体类的用@Id annotation批注的字段或属性上。

否则，JPA就会抛出一个exception

oracle.toplink.essentials.exceptions.QueryException
Exception Description: The primary key read from the row [DatabaseRecord(
orders.ID => null
orders.CREATE_DATE => 2009-05-27 00:00:00.0
orders.SUM_PRICE => 36817.0
orders.DESCRIPTION => This is an order creation example.
orders.cust_id => null)] during the execution of the query was detected to be null. Primary keys must not contain null.

再看一下关于Customer实体的映射，与Order不一样的地方，是discriminatorColumn=”customer_type” (可能为列别名)
加上这个属性的原因是，Customer类是一个父类，以供其他子类继承，而J PA的内在多态性机制将会获取到Customer的实际类型。根据J PA @Inheritance批注，得知，父类实体的表中必须有一个字段（默认为DTYPE）来表示各个子类的类型。所以当要将查询结果集保存为实体的时候，它必须要知道你所保存的这个Customer实体到底是哪种类型。
所以，你还必须在select子句中取得这个Discrimator Type的字段。
否则又会抛出异常：

oracle.toplink.essentials.exceptions.QueryException
Exception Description: Custom SQL failed to provide descriminator column : , as defined in SQLResultSetMapping : ReturnOrderListWithFullEntityType.

或者：

oracle.toplink.essentials.exceptions.QueryException
Exception Description: Custom SQL failed to provide descriminator column : customer_type, as defined in SQLResultSetMapping : ReturnOrderListWithPartEntityPartScalarType.

通过这种映射方式，我们可以推测，得到的结果集List中，数据会是这样：

[ {“Order对象1”, “Customer对象1”}, {“Order对象2”, “Customerr对象2”}, …… ]

经过运行测试程序，得到了我们的推论


*ReturnOrderListWithFullEntityType*
entity.Order@48edb5 entity.GoldenCustomer@1ee2c2c
entity.Order@1402d5a entity.GoldenCustomer@1ee2c2c
entity.Order@1e13e07 entity.GoldenCustomer@1ee2c2c
entity.Order@9cfec1 entity.GoldenCustomer@1ee2c2c
entity.Order@747fa2 entity.GoldenCustomer@1ee2c2c
……

看来的确是保存了对象，而且注意第二个对象不是Customer而是GoldenCustomer，这说明，JPA自动将数据映射进了GoldenCustomer实体（尽管我们使用的是Customer实体进行保存 “entityClass=entity.Customer.class”）

三、映射到实体与标量值的组合

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
@SqlResultSetMapping
    (
       name="ReturnOrderListWithPartEntityPartScalarType",
       entities=
       {
           @EntityResult
           (
              entityClass=entity.Order.class,
              fields=
              {
               @FieldResult(name="id",column="order_id"),
               @FieldResult(name="date",column="order_creation_date"),
               @FieldResult(name="desc",column="order_description"),
              @FieldResult(name="sum",column="order_sum_total")
              }
           ),
          
           @EntityResult
           (
              entityClass=entity.Customer.class,
              discriminatorColumn="customer_type",
              fields=
              {
                  @FieldResult(name="id",column="customer_id"),
                  @FieldResult(name="ctype",column="customer_type")
              }
           )
       },
       columns=
       {
           @ColumnResult(name="customer_name")
       }
    )

我们将结果集中与订单有关的保存进Order Entity，把与Customer有关的，将id和customer type 保存进Customer Entity，把customer name保存进标量。

经过运行测试程序，得到


*ReturnOrderListWithPartEntityPartScalarType*
entity.Order@48edb5 entity.GoldenCustomer@1ee2c2c John Smith
entity.Order@1402d5a entity.GoldenCustomer@1ee2c2c John Smith
entity.Order@1e13e07 entity.GoldenCustomer@1ee2c2c John Smith

综上所述，我们可以采取多种resultset映射机制来保存用本地查询得到的结果集，具体采取哪种要看具体的情况，要继续了解这方面的知识。